# makeIVEstimationDataFrame.R
# created 2012 July 21

makeIVEstimationDataFrame <- function (
  model.envir = IVModelsEnv, 
  df = NULL, 
  var.envir, 
  otherVarNames = NULL) {
  # This function returns a data frame containing all of the variables that I 
  # need for estimating my IV models with a dataset (e.g., the cumulative ANES
  # or the cumulative GSS).  The data frame can then be passed to the data 
  # argument of ivreg().  Using the data argument of ivreg() is useful when  
  # storing variables in environments other than the global environment.
  #
  # The function builds a list of variable names by inspecting all of the  
  # variables in model.envir (which should all have class `formula`) and by 
  # looking at othervarNames.  It searches in "df" for variables that have these 
  # names.  If df does not have variables with such names, the function looks 
  # for the variables in var.envir.  It returns a data frame consisting of 
  # all of the variables in df and all of the other variables in the list of 
  # variable names that it built.  [2012 07 21]
  if (! class(var.envir) %in% 'environment') {
    stop("var.envir must have class 'environment'")
  }
  if (! class(model.envir) %in% 'environment') {
    stop("model.envir must have class 'environment'")
  }
  if (!is.null(df) && !(class(df) %in% 'data.frame')) {
    stop("df must be NULL or have class 'data.frame'")
  }
  if (!is.null(otherVarNames) && !(class(otherVarNames) %in% 'character')) {
    stop("otherVarNames must be NULL or have class 'character'")
  }
  
  
  require(haven)  # for zap_labels()
  
  
  # BUILD THE LIST OF VARIABLE NAMES [2012 07 21]
  varNames <- unlist(eapply(model.envir, function (x) all.vars(x)[-1]))
  varNames <- unique(c(varNames, otherVarNames))
  varNames <- varNames[which(! varNames %in% colnames(df))]
  varNames <- varNames[!grepl('CA.fac', varNames)]  # We define CA.fac at the end of IV_setup.R.  

  # COLLECT THE VARIABLES AND RETURN A DATA FRAME [2012 07 21]
  varList  <- sapply(varNames, get, envir = var.envir, simplify = FALSE)
  if (length(varList) > 0) {
    sapply(varList, zap_labels) # TODO: need assignment to varList here
    vardf  <- data.frame(varList, df)
  } 
  else {
    vardf  <- df
  }
}
 